<HTML>
<TITLE>module moist_processes_mod</TITLE>
<BODY BGCOLOR="#AABBCC" TEXT="#332211" >

<DIV ALIGN="CENTER"> <FONT SIZE=1>
<A HREF="#INTERFACE">PUBLIC INTERFACE</A> / 
<A HREF="#ROUTINES">ROUTINES</A> / 
<A HREF="#NAMELIST">NAMELIST</A> / 
<A HREF="#DIAGNOSTICS">DIAGNOSTICS</A> / 
<A HREF="#CHANGES">CHANGES</A> / 
<A HREF="#ERRORS">ERRORS</A> / 
<A HREF="#PLANS">PLANS</A> 
</FONT>
<BR><BR></DIV><HR>


<H2>Module moist_processes_mod</H2>
<A NAME="HEADER">
<PRE>
     <B>Contact:</B>   Bruce Wyman or Steve Klein
     <B>Reviewers:</B>

     <B><A HREF=".doc.log#moist_processes.f90">Tags/Status</A></B>
</PRE>
</A><!-- END HEADER -->
<!--------------------------------------------------------------------->
<A NAME="OVERVIEW">
<HR>
<H4>OVERVIEW</H4>
<!-- BEGIN OVERVIEW -->
<PRE>

Controls the selection of most moisture processes, predicted cloud
schemes, and output of related diagnostic fields. Note that the
selection of prescribed clouds is not performed by this module.

</PRE>
</A><!-- END OVERVIEW -->
<!--------------------------------------------------------------------->
<A NAME="DESCRIPTION">
<!-- BEGIN DESCRIPTION -->
<PRE>
The following moisture processes (and predicted cloud schemes)
are controlled by this module:

    1) dry adiabatic adjustment
    2) moist convective adjustment
    3) relaxed Arakawa-Schubert
    4) large-scale condensation
    5) prognostic stratiform clouds
    6) basic relative humidity clouds
    7) (Gordon's) diagnostic clouds

</PRE>
</A><!-- END DESCRIPTION -->
<!--------------------------------------------------------------------->
<A NAME="MODULES_USED">
<HR>
<H4>OTHER MODULES USED</H4>
<!-- BEGIN MODULES_USED -->
<PRE>

       moist_conv_mod
      lscale_cond_mod
              ras_mod
      strat_cloud_mod
       diag_cloud_mod
        rh_clouds_mod
           clouds_mod
          dry_adj_mod
   sat_vapor_pres_mod
     physics_diag_mod
              fms_mod
        constants_mod
    field_manager_mod
   tracer_manager_mod

</PRE>
</A><!-- END MODULES_USED -->
<!--------------------------------------------------------------------->
<A NAME="INTERFACE">
<HR>
<H4>PUBLIC INTERFACE</H4>
<!-- BEGIN INTERFACE -->
<PRE>

use moist_processes_mod [,only: moist_processes_init,
                                moist_processes, moist_processes_end]

moist_processes_init - Must be called once before moist_processes to
                       initialize the module (reads namelist input and
                       restart file) and other modules used.

moist_processes      - Called every time step to compute convective
                       and large-scale precipitation and adjustments
                       to the temperature and specific humidity fields.

moist_processes_end  - Called at the end of the model run to terminate
                       the moist_processes module and other modules
                       used, also writes restart data.

Notes:
 1) A namelist interface controls runtime options and selects fields
    for diagnostics output.
 2) A restart file is generated by this module, although this file does
    not contain global data.
 3) No other data files are needed.

</PRE>
</A><!-- END INTERFACE -->
<!--------------------------------------------------------------------->
<A NAME="ROUTINES">
<HR>
<H4>PUBLIC ROUTINES</H4>
<!-- BEGIN ROUTINES -->
<PRE>

<b>call moist_processes_init</b> (id, jd, kd, axes, Time)

input

    id, jd    number of horizontal grid points in the global
              fields along the x and y axis, repectively.
                 [integer]

    kd        number of vertical points in a column of the atmosphere

    axes      The axis indices that are returned by previous calls to
              diag_axis_init. The values of this array correspond to the
              x, y, full (p-)level, and half (p-)level axes. These are the
              axes that diagnostic fields are output on.
                 [integer, dimension(4)]

    Time      The current time, used to initialize diagnostic fields.
                 [time_type]

---------------------------------------------------------------------

<b>call moist_processes</b> (is, ie, js, je, Time, dt, land,
                      phalf, pfull, omega,
                      t, q, r, u, v, tm, qm, rm, um, vm,
                      tdt, qdt, rdt, udt, vdt,
                      lprec, fprec, mask, kbot)

input

    is,ie      starting and ending i indices for window [integer]

    js,je      starting and ending j indices for window [integer]

    Time       The time used for saving diagnostic fields. [time_type]

    dt         time step in seconds (from t(n-1) to t(n+1) if leapfrog)
                 [real]

    land       fraction of surface covered by land
                 [real, dimension(:,:)]

    phalf      pressure at half levels in pascals
                 [real, dimension(:,:,nlev+1)]

    pfull      pressure at full levels in pascals
                 [real, dimension(:,:,nlev)]

    omega      omega (vertical velocity) at full levels
               in pascals per second
                 [real, dimension(:,:,nlev)]

    t, q       temperature (t) [deg k] and specific humidity
               of water vapor (q) [kg/kg] at full model levels,
               at the current time step if leapfrog scheme
                 [real, dimension(:,:,nlev)]

    r          tracer fields at full model levels, at the current
               time step if leapfrog; contains the fields needed by the
               stratiform cloud scheme if used
                 [real, dimension(:,:,nlev,ntrace)]

    u, v       zonal and meridional wind components [m/s] at full model
               levels, at the current time step if leapfrog scheme
                 [real, dimension(:,:,nlev)]

    tm, qm     temperature (t) [deg k] and specific humidity
               of water vapor (q) [kg/kg] at full model levels,
               at the previous time step if leapfrog scheme
                 [real, dimension(:,:,nlev)]

    rm         tracer fields at full model levels,
               at the previous time step if leapfrog
                 [real, dimension(:,:,nlev,ntrace)]

    um, vm     zonal and meridional wind components [m/s] at full model
               levels, at the previous time step if leapfrog scheme
                 [real, dimension(:,:,nlev)]

input/output

    tdt, qdt   temperature (tdt) [deg k/sec] and specific
               humidity of water vapor (qdt) tendency [1/sec]
                 [real, dimension(:,:,nlev)]

    rdt        tracer tendencies
                 [real, dimension(:,:,nlev,ntrace)]

    udt, vdt   zonal and meridional wind component tendencies [m/s2]
               at full model levels.  [real, dimension(:,:,nlev)]

output

    lprec      liquid precipitiaton rate (rain) in kg/m2/s
                 [real, dimension(:,:)]

    fprec      frozen precipitation rate (snow) in kg/m2/s
                 [real, dimension(:,:)]

input (optional)

    mask       mask (1. or 0.) for grid boxes above or below
               the ground, usually only necessary for the step-mountain
               (eta) vertical coordinate  [real, dimension(:,:,nlev)]

    kbot       index of the lowest model level, usually only necessary
               for the step-mountain (eta) vertical coordinate
                 [integer, dimension(:,:)]

---------------------------------------------------------------------

<b>call moist_processes_end</b> ( )

    There are no arguments to this routine.

</PRE>
</A><!-- END ROUTINES -->
<!--------------------------------------------------------------------->
<A NAME="NAMELIST">
<HR>
<H4>NAMELIST</H4>
<!-- BEGIN NAMELIST -->
<PRE>

<b>&moist_processes_nml</b>

  do_mca         Switch to turn on/off the moist convective adjustment
                 scheme.  [logical, default: do_mca=true ]

  do_lsc         Switch to turn on/off the large scale condensation
                 scheme.  [logical, default: do_lsc=true ]

  do_ras         Switch to turn on/off the relaxed Arakawa Shubert
                 convection scheme. Selecting this option may significantly
                 increase your program's cpu time.
                   [logical, default: do_ras=false ]

  do_strat       Switch to turn on/off the stratiform cloud scheme.
                 Selecting this option may significantly increase your
                 program's cpu time.  [logical, default: do_Strat=false ]

  do_dryadj      Switch to turn on/off the dry adiabatic adjustment scheme.
                 The dry adiabatic adjustment should not be used if the
                 Mellor-Yamada turbulence scheme has also been selected.
                   [logical, default: do_dryadj=false ]
 
  pdepth         Boundary layer depth (in pascals) for determining mean boundary
                 layer temperature used for snow versus rain determination in
                 MCA, LSC, and RAS.  [real, default: pdepth=150.e2]

  tfreeze        Mean temperature (in deg K) used for snow versus rain
                 determination in MCA, LSC, and RAS. If the mean boundary layer
                 temperature is less than or equal to Tfreeze then snow occurs.
                   [real, default: tfreeze=273.16]

  use_tau        Switch to determine whether data (temp, sphum, and tracers)
                 at the current time level (tau) or next time level (tau+1)
                 will used in the convective and large-scale schemes.
                   if use_tau = true then data at tau is used
                   if use_tau = false then data at tau+1 is used by explicitly
                                adding the tendency to the data at tau-1
                   [logical, default: use_tau=false ]

  do_rh_clouds   Switch to turn on/off simple relative humidity predicted
                 clouds. This option may only be selected when using the
                 large-scale condensation scheme (do_lsc=true) without the
                 diagnostic clouds (do_diag_clouds=false).
                   [logical, default: do_rh_clouds=false ]

  do_diag_clouds Switch to turn on/off (Gordon's) diagnostic cloud scheme.
                 This option may only be selected when using the large-scale
                 condensation scheme (do_lsc=true) without the simple relative
                 humidity clouds (do_rh_clouds=false).
                   [logical, default: do_diag_clouds=false ]
   
Notes:

  * do_mca and do_ras   cannot both be true
  * do_lsc and do_strat cannot both be true
  * do_rh_clouds and do_diag_clouds cannot both be true
  * do_rh_clouds can only be used with the large-scale condensation scheme,
      it will not operate when do_strat=true
  * pdepth and tfreeze are used to determine liquid vs. solid precipitation
      for MCA, LSC, and RAS schemes, the stratiform scheme determines it's
      own precipitation type.

</PRE>
</A><!-- END NAMELIST -->
<!--------------------------------------------------------------------->
<A NAME="DIAGNOSTICS">
<HR>
<H4>DIAGNOSTIC FIELDS</H4>
<PRE>
Diagnostic fields may be output to a netcdf file by specifying the
module name <b>moist</b> and the desired field names (given below)
in file <b>diag_table</b>. See the documentation for diag_manager.
</PRE>
<!-- BEGIN DIAGNOSTICS -->
<PRE>

Diagnostic fields for module name: <b>moist</b>

   field name   field description
   ----------   -----------------

   tdt_conv     temperature tendency from moist convective adjustment (MCA) or
                relaxed Arakawa-Schubert (RAS) [deg_K/s]
   qdt_conv     specific humidity tendency from MCA or RAS [kg/kg/s]
   prec_conv    total precipitation rate from MCA or RAS [kg/m2/s]
   snow_conv    frozen precipitation rate from MCA or RAS [kg/m2/s]
   t_conv_col   column integrated dry static energy tendency from 
                convection [W/m2]
   q_conv_col   column integrated water vapor tendency from convection [kg/m2/s]      
   tdt_ls       temperature tendency from large-scale condensation (LSC) or
                the stratiform cloud scheme (Strat) [deg_K/s]
   qdt_ls       specific humidity tendency from LSC or Strat [kg/kg/s]
   t_ls_col     column integrated dry static energy tendency from
                large-scale condensation or strat_cloud [W/m2]
   q_ls_col     column integrated water vapor tendency from large-scale
                condensation or strat_cloud [kg/m2/s]   
   prec_ls      total precipitation rate from LSC or Strat [kg/m2/s]
   snow_ls      frozen precipitation rate from LSC or Strat [kg/m2/s]
   precip       total precipitation rate (convective and large-scale) [kg/m2/s]
   WVP          column integrated water vapor [kg/m2]
   tdt_dadj     temperature tendency from dry convective adjustment [deg_K/s]
   rh           relative humidity after all adjustments [percent]
   mc           cumulus mass flux from RAS [kg/m2/s]
 
Note that the cumulus mass flux can only be output if the convection scheme 
selected is RAS (or donner deep?).

The following variables can be output only if the stratiform cloud scheme
is used:

   LWP          stratiform liquid water path [kg/m2]
   IWP          stratiform ice water path [kg/m2]
   AWP          stratiform saturated mass path [kg air/m2]; when AWP is 
                divided by the total column integrated mass (i.e. the 
		surface pressure divided by gravity), you have calculated 
		the fraction of air mass in the column which is saturated
		and part of a stratiform cloud.
   qldt_conv    stratiform cloud liquid specific humidity tendency from RAS 
                or donner deep [kg condensate/kg air/sec]
   qidt_conv    stratiform ice water specific humidity tendency from RAS or
                donner deep [kg condensate/kg air/sec]
   qadt_conv    cloud fraction tendency from RAS or donner deep [1/sec]
   ql_conv_col  LWP tendency from RAS or donner deep [kg condensate/m2/sec]
   qi_conv_col  IWP tendency from RAS or donner deep [kg condensate/m2/sec]
   qa_conv_col  AWP tendency from RAS or donner deep [kg air/m2/sec]
   qldt_ls      stratiform cloud liquid specific humidity tendency from  
                strat_cloud [kg condensate/kg air/sec]
   qidt_ls      stratiform ice water specific humidity tendency from 
                strat_cloud [kg condensate/kg air/sec]
   qadt_ls      cloud fraction tendency from strat_cloud [1/sec]
   ql_ls_col    LWP tendency from strat_cloud [kg condensate/m2/sec]
   qi_ls_col    IWP tendency from strat_cloud [kg condensate/m2/sec]
   qa_ls_col    AWP tendency from strat_cloud [kg air/m2/sec]
   
</PRE>
</A><!-- END DIAGNOSTICS -->
<!--------------------------------------------------------------------->
<A NAME="CHANGES">
<HR>
<H4>CHANGE HISTORY</H4>
<!-- BEGIN CHANGES -->
<PRE>
<B><A HREF=".doc.log#moist_processes.f90">Revision history</A></B>

<B>Changes prior to CVS version control</B>

<b>1/24/2000</b>

  * Fixed minor diagnostics bug that occurred if 
    no convective (or large-scale) scheme was selected.

<b>10/4/1999</b>

  * MPP version created. Minor changes for open_file, error_mesg,
    and Fortran write statements. Answers should reproduce the
    previous version.

  * Implementation of the new MPP diagnostics package. This required major
    changes to the diagnostic interface and the manner in which diagnostics
    quantities are selected.

<b>8/23/1999</b>

  * diagnostic output created for the cumulus mass flux from RAS scheme.

<b>5/26/1999</b>

  * interface changed (added momentum and momentum tendency) to allow
    cumulus friction momentum transport by RAS scheme

  * relative humidity diagnostics added

  * the diagnostic variable names that are actually written to
    the netcdf file have been shortened for compatibility with 
    various analysis packages

  * mask array multipications were removed, they are now done
    in specific moist processes routines

</PRE>
</A><!-- END CHANGES -->
<!--------------------------------------------------------------------->
<A NAME="ERRORS">
<HR>
<H4>ERROR MESSAGES</H4>
<!-- BEGIN ERRORS -->
<PRE>

<b>Fatal errors in moist_processes:</b>

    <b>moist_processes_init has not been called</b>
       You have not called moist_processes_init before calling
       moist_processes.

    <b>number of tracers less than nql or nqi or nqa.</b>
       The number of input tracers arguments is less than the 
       tracer number indices for the stratiform cloud scheme.
       You may not have declared enough tracers in your main program
       or you may have inadvertently selected the stratiform
       cloud scheme.

    <b>stratiform cloud tracer(s) not found</b>
       This code expects the field_table to define tracers
       called: <b>liq_wat</b>, <b>ice_wat</b>, and <b>cld_amt</b>.

    <b>tracers indices cannot be the same (i.e., nql=nqi=nqa).</b>
       The tracers numbers must all be unique (and non-zero).
       This error should not occur using the tracer manager.

    <b>temperatures not within range of es loopup table</b>
       A check of temperatures within moist_processes found
       temperatures outside the range of the saturation vapor
       lookup table. This usually means that the model has gone
       unstable and may be about the blow-up. Additional output
       was printed by moist processes that should indicated at
       what levels this problem occurred.

<b>Fatal errors in moist_processes_init:</b>

    <b>both do_mca and do_ras cannot be specified</b>
       Check namelist options do_mca and do_ras.

    <b>both do_lsc and do_strat cannot be specified</b>
       Check namelist options do_lsc and do_strat.
       

<b>Non-fatal notes in moist_processes_init:</b>

    <b>do_rh_clouds or do_diag_clouds + do_strat should not be specified</b>

    <b>do_rh_clouds and do_diag_clouds should not be specified</b>

    <b>both do_rh_clouds and do_strat should not be specified</b>
       This is not a FATAL error, only a NOTE.
       The relative humidity cloud scheme will not be used and
       the stratiform cloud scheme will override.
       Check namelist options do_rh_clouds and do_strat. 

</PRE>
</A><!-- END ERRORS -->
<!--------------------------------------------------------------------->
<A NAME="BUGS">
<HR>
<H4>KNOWN BUGS</H4>
<!-- BEGIN BUGS -->
<PRE>

     There are no known bugs.

</PRE>
</A><!-- END BUGS -->
<!--------------------------------------------------------------------->
<A NAME="PLANS">
<HR>
<H4>FUTURE PLANS</H4>
<!-- BEGIN PLANS -->
<PRE>

     None.

</PRE>
</A><!-- END PLANS -->
<!--------------------------------------------------------------------->

<HR>
</BODY>
</HTML>
